前天在編寫範例程式碼時，對於物件類別有點疑惑，所以今天就來花點時間研究 Reference 吧。

這邊以研究 JS 為主，JS 的 SDK 又有分為用於 Web 環境的 JavaScript ，以及用於 Server 環境（待查證）的 Node.js 兩種，但在單就 firebase.firestore 下的 API 目前看起來是沒有差異的。

依照類別與介面來分

以下是 firebase.firestore 下的類別與介面：

類別

• CollectionReference
• FieldPath
• GeoPoint
• QueryDocumentSnapshot
• Timestamp

介面

• Interfaces
• Blob
• DocumentChange
• DocumentReference
• DocumentSnapshot
• FieldValue
• Firestore
• FirestoreError
• GetOptions
• Query
• QuerySnapshot
• SetOptions
• Settings
• SnapshotListenOptions
• SnapshotMetadata
• SnapshotOptions
• Transaction
• WriteBatch

目前用過的

最一開始我們會透過 firebase.initializeApp() 去設定 Firebase 的連線資料，該方法的簽署式為：

firebase.initializeApp(options, name) returns firebase.app.App

不過目前我們只會用來設定，不會去管它的回傳值。在設定後，我們會透過 firebase.firestore() 取得 firebase.firestore.Firestore 的實例。而實例我們目前只用到也最常用到的方法如下：

- `collection(collectionPath) returns firebase.firestore.CollectionReference`
- `doc(documentPath) returns firebase.firestore.DocumentReference`

可以看到這兩個方法分別會得到集合參照（CollectionReference）和文件參照（DocumentReference）。其中集合參照又擴充自 firebase.firestore.Query，所以我們就先來看看 Query 提供的方法吧！

首先是用來查詢用的相關方法，這些方法都回傳 Query，所以我們可以用方法鏈的方式將所有查詢資訊串起來。至於這些方法還沒提到的部分，就等之後再另外開一篇吧。

• where(fieldPath, opStr, value) returns firebase.firestore.Query
• orderBy(fieldPath, directionStr) returns firebase.firestore.Query
• limit(limit) returns firebase.firestore.Query
• startAt(snapshotOrVarArgs) returns firebase.firestore.Query
• endAt(snapshotOrVarArgs) returns firebase.firestore.Query
• startAfter(snapshotOrVarArgs) returns firebase.firestore.Query
• endBefore(snapshotOrVarArgs) returns firebase.firestore.Query

而呼叫以上方法時，還不會馬上對 Cloud Firestore 提出 request，而是等到使用 get() 方法時才會去抓取資料。

• get(options) returns firebase.firestore.QuerySnapshot

而 get() 方法，就會回傳原型為 firebase.firestore.QuerySnapshot 的物件。這個原型提供幾個：

• docs: 回傳不為 null 的 Array，且裡面都是以 firebase.firestore.QueryDocumentSnapshot 為原型且不為 null 的物件。
• empty: 布林值。
• query: 回傳讓我們得到這個 QuerySnapshot 的 Query
• size: 回傳數字。

方法中我們目前有用到的就是：

• forEach(callback, thisArg)

forEach 中的 callback 的簽署式則是：

• function(non-null firebase.firestore.QueryDocumentSnapshot)

也就是會迭代回傳以 QueryDocumentSnapshot 為原型的物件，讓我們透過其方法去取得我們要的資料，方法如下：

• data(options) returns (firebase.firestore.Firestore~DocumentData or undefined)
• get(fieldPath, options) returns (any type or undefined)

前者是拿取該文件的所有資料，後者則是拿取該文件指定欄位的資料。到這邊就算是把集合到資料的流程順過一次了。然後我們再度回到透過 firebase.firestore.Firestore.doc() 取得的 DocumentReference 吧！

先從我們前面提到過的獲取、新增、更新、刪除，也就是 CRUD 的四個方法吧！

• get(options) returns Promise containing non-null firebase.firestore.DocumentSnapshot
• set(data, options) returns Promise containing void
• update(...var_args) returns Promise containing void
• delete() returns Promise containing void

可以看到四個方法都會返回 Promise 物件，我們才因此得以使用 then() 和 catch() 去處理成功和失敗的狀況，其中 get() 方法的 Promise 會包含 DocumentSnapshot，而前面提到的 QueryDocumentSnapshot 正是擴充自 DocumentSnapshot，所以兩者擁有相同的方法介面，所以方法這邊就不重複提了。

回到 DocumentReference 的 collection() 方法，該方法會讓我們拿到 CollectionReference：

• collection(collectionPath) returns firebase.firestore.CollectionReference

而 CollectionReference 又提供 doc() 方法讓我們拿到 CollectionReference：

• doc(documentPath) returns firebase.firestore.DocumentReference

所以我們就可以透過這種方式從集合中拿到某文件，再從文件拿到他下面的某個集合，依此類推。而 CollectionReference 除了比 Query 多出了 doc() 方法外，還有我們之前用來新增資料的 `add() 方法：

• add(data) returns Promise containing non-null firebase.firestore.DocumentReference

到了這邊，前面提過的方法和得到的物件原型/類別都大概提過了，感覺在認知是有比較有系統了呢。那我們明天再繼續研究下去吧！